<?php
/**
 * Handler
 * 
 * @category	Session
 * @package		dayscript.session
 * @subpackage	
 * @author		Nelson Daza <ndaza@dayscript.com>
 * @copyright	2009 Dayscript Ltda.
 * @license		
 * @version		1.0
 * @version		$Revision: 0 $
 * @filesource	
 * @link		http://www.dayscript.com
 * @link		{docsLink}
 * @uses		
 * @since		1.0
 * @modifiedby	$LastChangedBy: Nelson Daza $
 * @modified	$Date: 2009-08-13 $
 */

namespace dayscript\session;

/**
 * Handler
 *
 * Interface
 * 
 * @category	Session
 * @package		dayscript.session
 * @subpackage	
 * @author		Nelson Daza <ndaza@dayscript.com>
 * @copyright	2009 Dayscript Ltda.
 * @license		
 * @version		1.0
 * @link		http://www.dayscript.com
 * @link		{docsLink}
 * @uses		
 * @since		1.0
 * @modifiedby	$LastChangedBy: Nelson Daza $
 * @modified	$Date: 2009-08-13 $
 */
interface Handler	{
	/**
	 * Open Session - retrieve resources
	 * 
	 * This works like a constructor in classes and is executed when the session is being opened. 
	 * The open function expects two parameters, where the first is the save path and the second is the session name. 
	 * 
	 * @param string $saveDir Directory where the data is stored  
	 * @param string $sessionName Data to open
	 * @return boolean $success
	 */
	public function open( $saveDir, $sessionName );
	/**
	 * Close Session - free resources
	 * 
	 * This works like a destructor in classes and is executed when the session operation is done. 
	 * @return boolean $success
	 */
	public function close( );
	/**
	 * Read session data
	 * 
	 * Read function must return string value always to make save handler work as expected. 
	 * Return empty string if there is no data to read. 
	 * Return values from other handlers are converted to boolean expression. TRUE for success, FALSE for failure. 
	 * 
	 * @param string $sessionId
	 * @return string $readed
	 */
	public function read( $sessionId );
	/**
	 * Write Session data to resource
	 * 
	 * Note: The "write" handler is not executed until after the output stream is closed.
	 * Thus, output from debugging statements in the "write" handler will never be seen in the browser.
	 * If debugging output is necessary, it is suggested that the debug output be written to a file instead. 
	 * 
	 * @param string $sessionId
	 * @param mixed $data
	 * @return boolean $success
	 */
	public function write( $sessionId, $data );
	/**
	 * Destroy Session data from resource for given session id
	 * 
	 * This is executed when a session is destroyed with session_destroy( ). 
	 * 
	 * @param string $sessionId
	 * @return boolean $success
	 */
	public function destroy( $sessionId );
	/**
	 * Garbage Collection - remove old session data older than $maxlifetime (in seconds)
	 * 
	 * This is executed when the session garbage collector is executed. 
	 * 
	 * @param int $maxlifetime
	 * @return boolean $success
	 */
	public function gc( $maxlifetime );
}